com.nec.tdd.tools.dbMapper
Interface DBInterface

All Superinterfaces:
DataSource
All Known Implementing Classes:
com.nec.tdd.tools.dbMapper.ORDBMapper

public interface DBInterface
extends DataSource

This interface provides an object-oriented view of data stored in relation database tables. It encapsulates all database operations such as creating, updating, querying, and deleting objects in the relation database.

It also allows custom database operations (e.g. a custom SQL statement, get database connection etc) to be defined and executed for any class that needs to extend or modify the default processing.

DBInterface defines methods that allow an user to manage transaction boundaries across DBInterface create, update, delete methods. If user transaction is not active (beginTransaction is not invoked) for current thread, a method call is treated as an atomic operation (transaction boundary).

 

Following terminology is used throughout the db module documentation :

Terminology:

Basic type:

At present, supported basic types are:
int, short, byte, char, long, float, double, String, StringBuffer, Integer, Short, Byte, Char, Long, Float, Double.
Ex: basic type : int, String
        not a basic type : StringBuffer, myPkg.myClass

Key attribute:

An attribute which is one of the database keys for a mapping entry (isKey set to true).
A key attribute must be of basic type.

Non-key attribute:

An mapping entry attribute which is not a key (isKey == false). Non-key attributes can be of any of the following types:

Primary key:

A class (in OR mapping file) is said to have a primary key if: Note: If both of the above conditions are met, expilicit key class is used.


Method Summary
 void beginTransaction()
          Create a new transaction and associate it with the current thread.
 void commitTransaction()
          Complete the transaction associated with the current thread.
 void create(java.lang.Object userObject)
          This generic insert/create method stores user object to database associated with this DBInterface.
 void createTree(java.lang.Object userObject)
          This generic insert/create method stores user object(whole object containment tree *Note1) to database associated with this DBInterface.
 void createTree(java.lang.Object userObject, int depth)
          This method is similar to the createTree(Object) method, with only difference that user can specify maximum recursion depth.
 boolean delete(java.lang.Object userObject)
          This generic delete method deletes an user object (if found) from database associated with this DBInterface.
 int deleteAll(java.lang.Class userObjectClass)
          This generic method deletes all persistent user objects of given class type from the database.
 int deleteByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass)
          This generic delete method deletes user object whose attribute values matches with those specified in attribute value map.
 boolean deleteByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass)
          This generic delete method deletes an user object, if found, (from database associated with this DBInterface) based on primary key.
 java.sql.ResultSet executeQuery(java.lang.String query)
          Executes an SQL statement that returns a single ResultSet object.
 int executeUpdate(java.lang.String query)
          Executes an SQL INSERT, UPDATE or DELETE statement.
 java.util.Collection findAll(java.lang.Class userObjectClass)
          This generic finder method returns collection of all user object stored in database.
 java.util.Collection findAllPrimaryKeys(java.lang.Class userObjectClass)
          This generic finder method returns collection of all primary keys associated with a user object stored in database.
 java.util.Collection findByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass)
          This generic finder method returns a collection of user object whose attribute values matches with those specified in attribute value map.
 java.lang.Object findByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass)
          This generic finder method returns a user object, if found, (from database associated with this DBInterface) based on the primary key.
 java.lang.Object findByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass, int depth)
          This generic finder method loads partial or whole user object containment tree, if found, (from database associated with this DBInterface) based on the primary key and depth parameters.
 java.util.Collection findByQuery(java.lang.String query, java.lang.Class userObjectClass)
          This generic finder method returns a collection of user object based on the user SQL query.
 java.util.Collection findPrimaryKeysByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass)
          This generic finder method returns a collection of primary key objects based on given attribute value map.
 java.util.Collection findPrimaryKeysByQuery(java.lang.String query, java.lang.Class userObjectClass)
          This generic finder method returns a collection of primary key objects based on the user SQL query.
 boolean isActiveTransaction()
          Obtain the status of the transaction associated with the current thread.
 void rollbackTransaction()
          Rollback the transaction associated with the current thread.
 boolean update(java.lang.Object userObject)
          This generic update method updates all basic non-key attributes of an user object (if found) to database associated with this DBInterface.
 boolean update(java.lang.Object userObject, AttrValMap attrValMap, boolean bUpdateUserObject)
          This generic update method updates only the specified attributes (basic or non-basic) of an user object (if found) to database associated with this DBInterface.
 boolean update(java.lang.Object userObject, java.util.HashMap attrValMap, boolean bUpdateUserObject)
          This method is similar to the update(Object,HashMap,boolean) method, with only difference that attribute names and values are passed in HashMap instead of AttrValMap.
Note: Java primitive types should be wrapped in objects (ex.
 boolean updateTree(java.lang.Object userObject)
          This generic update method updates all non-key attributes of an user object (if found) to database associated with this DBInterface.
 boolean updateTree(java.lang.Object userObject, int depth)
          This method is similar to the updateTree(Object) method, with only difference that user can specify maximum recursion depth.
 
Methods inherited from interface com.nec.tdd.tools.dbMapper.DataSource
getConnection, releaseConnection
 

Method Detail

create

public void create(java.lang.Object userObject)
            throws java.lang.Exception
This generic insert/create method stores user object to database associated with this DBInterface. This method only saves basic type attributes, non-basic attributes are ignored. Use createTree methods to save both basic and non-basic attributes.

Assumption:An OR mapping exists for this user object (class type) in mapping file.

Parameters:
userObject - The user object to be inserted.
Throws:
Exception - if any problems in saving the user object.
See Also:
createTree(Object), createTree(Object,int)

createTree

public void createTree(java.lang.Object userObject)
                throws java.lang.Exception
This generic insert/create method stores user object(whole object containment tree *Note1) to database associated with this DBInterface. This method recursively tries to save both basic and non-basic attributes which fall below maximum recursion depth (see Constants.MAX_DEPTH).
Note1: tree depth bounded by maximum recursion depth.

Assumption: An OR mapping exists for the user object and all non-basic type attributes in the mapping file.

Parameters:
userObject - The user object (tree root) to be inserted.
Throws:
Exception - if any problems in saving the user object.
See Also:
create(Object), createTree(Object,int)

createTree

public void createTree(java.lang.Object userObject,
                       int depth)
                throws java.lang.Exception
This method is similar to the createTree(Object) method, with only difference that user can specify maximum recursion depth. The attributes below this depth will not be stored in the databse.

depth = 1 is equivalent to create(Object).
depth = Constants.MAX_DEPTH is equivalent to createTree(Object) method.

Parameters:
userObject - The user object (tree root) to be inserted.
depth - The maximum recursion depth.
Throws:
Exception - if any problems in saving the user object.
See Also:
create(Object), createTree(Object)

delete

public boolean delete(java.lang.Object userObject)
               throws java.lang.Exception
This generic delete method deletes an user object (if found) from database associated with this DBInterface.

Assumption: An OR mapping exists for this user object (class type) in mapping file.

Parameters:
userObject - The user object to be deleted.
Returns:
If user object was found and deleted, false otherwise.
Throws:
Exception - if any problems in deleting the user object.

deleteByPrimaryKey

public boolean deleteByPrimaryKey(java.lang.Object primaryKey,
                                  java.lang.Class userObjectClass)
                           throws java.lang.Exception
This generic delete method deletes an user object, if found, (from database associated with this DBInterface) based on primary key.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) primaryKey class exists.

Parameters:
primaryKey - The primaryKey based on which user object of type userObjectClass is deleted.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
If user object was found and deleted, false otherwise.
Throws:
Exception - if any problems in deleting the user object.

deleteByAttributes

public int deleteByAttributes(AttrValMap attrValMap,
                              java.lang.Class userObjectClass)
                       throws java.lang.Exception
This generic delete method deletes user object whose attribute values matches with those specified in attribute value map. Attributes specified in attrValMap need not be of key type.

This method is equivalent to deleteByPrimaryKey(pkey, userObjectClass) method if all the key attributes for this userObjectClass type are specified in the attrValMap.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) AttrValMap attributes are valid userObjectClass attribute names (specified in mapping file).

Parameters:
attrValMap - Map of attributes and values based on which user objects of type userObjectClass is deleted.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Number of deleted user objects.
Throws:
Exception - if any databse problems in deleting the user objects.

deleteAll

public int deleteAll(java.lang.Class userObjectClass)
              throws java.lang.Exception
This generic method deletes all persistent user objects of given class type from the database. Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
Parameters:
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Number of deleted user objects.
Throws:
java.lang.Exception - if any databse problems in deleting the user objects.

update

public boolean update(java.lang.Object userObject)
               throws java.lang.Exception
This generic update method updates all basic non-key attributes of an user object (if found) to database associated with this DBInterface. This method only saves basic type of attributes; non-basic attributes are ignored. Use updateTree methods to save both basic and non-basic non-key attributes.

Assumptions:
1) An OR mapping exists for this user object (class) in mapping file.
2) Only non-key non-basic attributes are saved.
3) Original KEY attribues are not modified by user.

Parameters:
userObject - The user object to be updated.
Returns:
If user object was found and updated, false otherwise.
Throws:
Exception - if any problems in updating the user object.
See Also:
updateTree(Object), updateTree(Object,int), update(Object,AttrValMap,boolean), update(Object,HashMap,boolean)

updateTree

public boolean updateTree(java.lang.Object userObject)
                   throws java.lang.Exception
This generic update method updates all non-key attributes of an user object (if found) to database associated with this DBInterface. This method recursively tries to save both basic and non-basic non-key attributes which fall below maximum recursion depth (see Constants.MAX_DEPTH).

Assumptions:
1) An OR mapping exists for the user object and all non-basic type attributes in the mapping file.
2) Only non-key attributes are saved.
3) Original KEY attribues are not modified by user.

Parameters:
userObject - The user object to be updated.
Returns:
If user object was found and updated, false otherwise.
Throws:
Exception - if any problems in updating the user object.
See Also:
updateTree(Object,int), update(Object,AttrValMap,boolean), update(Object,HashMap,boolean), update(Object)

updateTree

public boolean updateTree(java.lang.Object userObject,
                          int depth)
                   throws java.lang.Exception
This method is similar to the updateTree(Object) method, with only difference that user can specify maximum recursion depth. The attributes below this depth will not be stored in the databse.

depth = 1 is equivalent to update(Object).
depth = Constants.MAX_DEPTH is equivalent to updateTree(Object) method.

Parameters:
userObject - The user object (tree root) to be inserted.
depth - The maximum recursion depth.
Returns:
If user object was found and updated, false otherwise.
Throws:
Exception - if any problems in saving the user object.
See Also:
updateTree(Object), update(Object,AttrValMap,boolean), update(Object,HashMap,boolean), update(Object)

update

public boolean update(java.lang.Object userObject,
                      AttrValMap attrValMap,
                      boolean bUpdateUserObject)
               throws java.lang.Exception
This generic update method updates only the specified attributes (basic or non-basic) of an user object (if found) to database associated with this DBInterface.

Assumptions:
1) An OR mapping exists for this user object (class type) in mapping file
2) Only non-key attributes are listed in attrValMap and original KEY attribues are not modified by user.

Parameters:
userObject - The user object to be updated.
attrValMap - Map of attributes and values to be updated
bUpdateUserObject - Indicates whether or not after successful database update, to apply attrValMap changes on user object.
Returns:
If user object was found and updated, false otherwise.
Throws:
java.lang.Exception - if any problems in updating the user object.
See Also:
update(Object,HashMap,boolean), update(Object), updateTree(Object), updateTree(Object,int)

update

public boolean update(java.lang.Object userObject,
                      java.util.HashMap attrValMap,
                      boolean bUpdateUserObject)
               throws java.lang.Exception
This method is similar to the update(Object,HashMap,boolean) method, with only difference that attribute names and values are passed in HashMap instead of AttrValMap.
Note: Java primitive types should be wrapped in objects (ex. long in java.util.Long)
Parameters:
userObject - The user object to be updated.
attrValMap - Map of attributes and values to be updated
bUpdateUserObject - Indicates whether or not after successful database update, to apply attrValMap changes on user object.
Returns:
If user object was found and updated, false otherwise.
Throws:
java.lang.Exception - if any problems in updating the user object.
See Also:
update(Object,AttrValMap,boolean), update(Object), updateTree(Object), updateTree(Object,int)

findByPrimaryKey

public java.lang.Object findByPrimaryKey(java.lang.Object primaryKey,
                                         java.lang.Class userObjectClass)
                                  throws java.lang.Exception
This generic finder method returns a user object, if found, (from database associated with this DBInterface) based on the primary key. Only basic attributes are filled in user object. Use findByPrimaryKey(Object,Class,int) method to load non-basic attributes or to load whole or partial object tree.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) PrimaryKey class exists (refer to Terminology section).

Parameters:
primaryKey - The primaryKey based on which user object of type userObjectClass is returned.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
The user object of type userObjectClass (if found). Null if object can not be located.
Throws:
java.lang.Exception - if any databse problems in finding the user object.
See Also:
findByPrimaryKey(Object,Class,int), findByAttributes(AttrValMap,Class), findByQuery(String,Class), findAll(Class)

findByPrimaryKey

public java.lang.Object findByPrimaryKey(java.lang.Object primaryKey,
                                         java.lang.Class userObjectClass,
                                         int depth)
                                  throws java.lang.Exception
This generic finder method loads partial or whole user object containment tree, if found, (from database associated with this DBInterface) based on the primary key and depth parameters. This method recursively tries to load both basic and non-basic attributes of user objects (contained within user object containment tree) which fall below specified recursion depth parameter.

Assumptions:
1) An OR mapping exists for the userObjectClass and all non-basic type attributes in the mapping file.
2) PrimaryKey class exists (refer to Terminology section).

Parameters:
primaryKey - The primaryKey based on which user object of type userObjectClass is returned.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
depth - The maximum recursion depth.
Returns:
The user object of type userObjectClass (if found). Null if object can not be located.
Throws:
java.lang.Exception - if any databse problems in finding the user object.
See Also:
findByPrimaryKey(Object,Class), findByAttributes(AttrValMap,Class), findByQuery(String,Class), findAll(Class)

findByAttributes

public java.util.Collection findByAttributes(AttrValMap attrValMap,
                                             java.lang.Class userObjectClass)
                                      throws java.lang.Exception
This generic finder method returns a collection of user object whose attribute values matches with those specified in attribute value map. Only basic attributes are filled in user object. Attributes specified in attrValMap need not be of key type. This method is equivalent to findByPrimaryKey(pkey, userObjectClass) method if all the key attributes for this userObjectClass type are specified in the attrValMap.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) AttrValMap attributes are valid userObjectClass attribute names (specified in mapping file).
3) AttrValMap contains atleast one entry.

Parameters:
attrValMap - Map of attributes and values based on which user objects of type userObjectClass is returned.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of user objects of type userObjectClass.
Throws:
java.lang.Exception - if any databse problems in finding the user objects.
See Also:
findAll(Class), findByQuery(String,Class), findByPrimaryKey(Object,Class), findByPrimaryKey(Object,Class,int)

findByQuery

public java.util.Collection findByQuery(java.lang.String query,
                                        java.lang.Class userObjectClass)
                                 throws java.lang.Exception
This generic finder method returns a collection of user object based on the user SQL query. Only basic attributes are filled in user object. One should use this method only none of other finder methods (findByPrimaryKey, findByAttributes etc) solve the purpose. This method is most flexible of all the finder methods but requires SQL details in user code.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) Valid user SQL query, which should return rows that contains all the attributes/columns in userObjectClass.

Parameters:
query - User SQL query.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of user objects of type userObjectClass.
Throws:
java.lang.Exception - if any databse problems in finding the user objects or executing the query.
See Also:
findByAttributes(AttrValMap,Class), findAll(Class), findByPrimaryKey(Object,Class), findByPrimaryKey(Object,Class,int)

findAll

public java.util.Collection findAll(java.lang.Class userObjectClass)
                             throws java.lang.Exception
This generic finder method returns collection of all user object stored in database. Only basic attributes are filled in user object.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.

Parameters:
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of user objects of type userObjectClass.
Throws:
java.lang.Exception - if any databse problems in finding the user objects.
See Also:
findByAttributes(AttrValMap,Class), findByQuery(String,Class), findByPrimaryKey(Object,Class), findByPrimaryKey(Object,Class,int)

findPrimaryKeysByAttributes

public java.util.Collection findPrimaryKeysByAttributes(AttrValMap attrValMap,
                                                        java.lang.Class userObjectClass)
                                                 throws java.lang.Exception
This generic finder method returns a collection of primary key objects based on given attribute value map. Attributes specified in attrValMap need not be of key type.

Assumptions:
1) An OR mapping exists for the userObjectClass in mapping file.
2) AttrValMap attributes are valid userObjectClass attribute names (specified in mapping file).
3) AttrValMap contains atleast one entry.
4) primaryKey class exists.

Parameters:
attrValMap - Map of attributes and values based on which primary key objects associated with userObjectClass is returned.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of primary key objects associated with userObjectClass. Values are automatically wrapped if primary key class has a java primitive type.
Throws:
java.lang.Exception - if any databse problems in finding the primary keys.
See Also:
findPrimaryKeysByQuery(String,Class), findAllPrimaryKeys(Class)

findPrimaryKeysByQuery

public java.util.Collection findPrimaryKeysByQuery(java.lang.String query,
                                                   java.lang.Class userObjectClass)
                                            throws java.lang.Exception
This generic finder method returns a collection of primary key objects based on the user SQL query. One should use this method only none of other primary key finder methods (findPrimaryKeysByAttributes, findAllPrimaryKeys etc) solve the purpose. This method is most flexible of all the primary key finder methods but requires SQL details in user code.

Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) Valid user SQL query, which should return rows that contains all the key attributes/columns in userObjectClass.
3) primaryKey class exists.

Parameters:
query - User SQL query.
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of primary key objects associated with userObjectClass. Values are automatically wrapped if primary key class has a java primitive type.
Throws:
java.lang.Exception - if any databse problems in finding the primary keys or executing the query.
See Also:
findPrimaryKeysByAttributes(AttrValMap,Class), findAllPrimaryKeys(Class)

findAllPrimaryKeys

public java.util.Collection findAllPrimaryKeys(java.lang.Class userObjectClass)
                                        throws java.lang.Exception
This generic finder method returns collection of all primary keys associated with a user object stored in database.

Assumptions:
An OR mapping exists for this userObjectClass in mapping file.

Parameters:
userObjectClass - The user object class type (ex. HashMap.class gives HashMap class type).
Returns:
Collection of primary key objects associated with userObjectClass. Values are automatically wrapped if primary key class has a java primitive type.
Throws:
java.lang.Exception - if any databse problems in finding the primary keys or executing the query.
See Also:
findPrimaryKeysByAttributes(AttrValMap,Class), findPrimaryKeysByQuery(String,Class)

beginTransaction

public void beginTransaction()
                      throws java.lang.Exception
Create a new transaction and associate it with the current thread. It allows an application to explicitly manage transaction boundaries. Any DBInterface method called after successful invocation of this method, will be part of this transaction. This module will use same database resource (connection) and apply results to database only when user explicitly terminates transaction for the thread.
Throws:
java.lang.Exception - Thrown if the thread is already associated with a transaction or no available resource.
See Also:
isActiveTransaction(), commitTransaction(), rollbackTransaction()

isActiveTransaction

public boolean isActiveTransaction()
Obtain the status of the transaction associated with the current thread. If no transaction is associated with the current thread, this method returns false.
Returns:
The transaction status.
See Also:
beginTransaction(), commitTransaction(), rollbackTransaction()

commitTransaction

public void commitTransaction()
                       throws java.lang.Exception
Complete the transaction associated with the current thread. When this method completes, the thread becomes associated with no transaction.
Throws:
java.lang.Exception - Thrown if the thread is not associated with a transaction or any databse problems during database commit.
See Also:
rollbackTransaction(), beginTransaction(), isActiveTransaction()

rollbackTransaction

public void rollbackTransaction()
                         throws java.lang.Exception
Rollback the transaction associated with the current thread. When this method completes, the thread becomes associated with no transaction.
Throws:
java.lang.Exception - Thrown if the thread is not associated with a transaction or any databse problems during database rollback.
See Also:
commitTransaction(), beginTransaction(), isActiveTransaction()

executeQuery

public java.sql.ResultSet executeQuery(java.lang.String query)
                                throws java.lang.Exception
Executes an SQL statement that returns a single ResultSet object. User should close result set before invoking another db interface method.
Parameters:
query - typically this is a static SQL SELECT statement.
Returns:
a ResultSet object that contains the data produced by the given query; never null.
Throws:
java.lang.Exception - if a database error occurs.
See Also:
Statement.executeQuery(String)

executeUpdate

public int executeUpdate(java.lang.String query)
                  throws java.lang.Exception
Executes an SQL INSERT, UPDATE or DELETE statement.
Parameters:
query - an SQL INSERT, UPDATE or DELETE statement or an SQL statement that returns nothing
Returns:
either the row count for INSERT, UPDATE or DELETE statements, or 0 for SQL statements that return nothing.
Throws:
java.lang.Exception - if a database error occurs.
See Also:
Statement.executeUpdate(String)