|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 :
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 |
public void create(java.lang.Object userObject) throws java.lang.Exception
Assumption:An OR mapping exists for this user object (class type) in mapping file.
userObject
- The user object to be inserted.Exception
- if any problems in saving the
user object.createTree(Object)
,
createTree(Object,int)
public void createTree(java.lang.Object userObject) throws java.lang.Exception
Assumption: An OR mapping exists for the user object and all non-basic type attributes in the mapping file.
userObject
- The user object (tree root) to be inserted.Exception
- if any problems in saving the user
object.create(Object)
,
createTree(Object,int)
public void createTree(java.lang.Object userObject, int depth) throws java.lang.Exception
depth = 1 is equivalent to create(Object).
depth = Constants.MAX_DEPTH is equivalent to createTree(Object) method.
userObject
- The user object (tree root) to be inserted.depth
- The maximum recursion depth.Exception
- if any problems in saving the user
object.create(Object)
,
createTree(Object)
public boolean delete(java.lang.Object userObject) throws java.lang.Exception
Assumption: An OR mapping exists for this user object (class type) in mapping file.
userObject
- The user object to be deleted.Exception
- if any problems in deleting the user
object.public boolean deleteByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass) throws java.lang.Exception
Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) primaryKey class exists.
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).Exception
- if any problems in deleting the user
object.public int deleteByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass) throws java.lang.Exception
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).
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).Exception
- if any databse problems in deleting
the user objects.public int deleteAll(java.lang.Class userObjectClass) throws java.lang.Exception
userObjectClass
- The user object class type (ex.
HashMap.class gives HashMap class type).java.lang.Exception
- if any databse problems in deleting the user objects.public boolean update(java.lang.Object userObject) throws java.lang.Exception
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.
userObject
- The user object to be updated.Exception
- if any problems in updating the user
object.updateTree(Object)
,
updateTree(Object,int)
,
update(Object,AttrValMap,boolean)
,
update(Object,HashMap,boolean)
public boolean updateTree(java.lang.Object userObject) throws java.lang.Exception
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.
userObject
- The user object to be updated.Exception
- if any problems in updating the
user object.updateTree(Object,int)
,
update(Object,AttrValMap,boolean)
,
update(Object,HashMap,boolean)
,
update(Object)
public boolean updateTree(java.lang.Object userObject, int depth) throws java.lang.Exception
depth = 1 is equivalent to update(Object).
depth = Constants.MAX_DEPTH is equivalent to updateTree(Object) method.
userObject
- The user object (tree root) to be inserted.depth
- The maximum recursion depth.Exception
- if any problems in saving the
user object.updateTree(Object)
,
update(Object,AttrValMap,boolean)
,
update(Object,HashMap,boolean)
,
update(Object)
public boolean update(java.lang.Object userObject, AttrValMap attrValMap, boolean bUpdateUserObject) throws java.lang.Exception
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.
userObject
- The user object to be updated.attrValMap
- Map of attributes and values to be updatedbUpdateUserObject
- Indicates whether or not after successful
database update, to apply
attrValMap changes on user object.java.lang.Exception
- if any problems in updating the user object.update(Object,HashMap,boolean)
,
update(Object)
,
updateTree(Object)
,
updateTree(Object,int)
public boolean update(java.lang.Object userObject, java.util.HashMap attrValMap, boolean bUpdateUserObject) throws java.lang.Exception
userObject
- The user object to be updated.attrValMap
- Map of attributes and values to be updatedbUpdateUserObject
- Indicates whether or not after successful
database update, to apply
attrValMap changes on user object.java.lang.Exception
- if any problems in updating the user object.update(Object,AttrValMap,boolean)
,
update(Object)
,
updateTree(Object)
,
updateTree(Object,int)
public java.lang.Object findByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass) throws java.lang.Exception
Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
2) PrimaryKey class exists (refer to Terminology section).
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).java.lang.Exception
- if any databse problems in finding the user object.findByPrimaryKey(Object,Class,int)
,
findByAttributes(AttrValMap,Class)
,
findByQuery(String,Class)
,
findAll(Class)
public java.lang.Object findByPrimaryKey(java.lang.Object primaryKey, java.lang.Class userObjectClass, int depth) throws java.lang.Exception
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).
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.java.lang.Exception
- if any databse problems in finding the user object.findByPrimaryKey(Object,Class)
,
findByAttributes(AttrValMap,Class)
,
findByQuery(String,Class)
,
findAll(Class)
public java.util.Collection findByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass) throws java.lang.Exception
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.
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).java.lang.Exception
- if any databse problems in finding the user objects.findAll(Class)
,
findByQuery(String,Class)
,
findByPrimaryKey(Object,Class)
,
findByPrimaryKey(Object,Class,int)
public java.util.Collection findByQuery(java.lang.String query, java.lang.Class userObjectClass) throws java.lang.Exception
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.
query
- User SQL query.userObjectClass
- The user object class type (ex. HashMap.class
gives HashMap class type).java.lang.Exception
- if any databse problems in finding the user
objects or executing the query.findByAttributes(AttrValMap,Class)
,
findAll(Class)
,
findByPrimaryKey(Object,Class)
,
findByPrimaryKey(Object,Class,int)
public java.util.Collection findAll(java.lang.Class userObjectClass) throws java.lang.Exception
Assumptions:
1) An OR mapping exists for this userObjectClass in mapping file.
userObjectClass
- The user object class type (ex.
HashMap.class gives HashMap class type).java.lang.Exception
- if any databse problems in finding the user objects.findByAttributes(AttrValMap,Class)
,
findByQuery(String,Class)
,
findByPrimaryKey(Object,Class)
,
findByPrimaryKey(Object,Class,int)
public java.util.Collection findPrimaryKeysByAttributes(AttrValMap attrValMap, java.lang.Class userObjectClass) throws java.lang.Exception
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.
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).java.lang.Exception
- if any databse problems in finding the primary keys.findPrimaryKeysByQuery(String,Class)
,
findAllPrimaryKeys(Class)
public java.util.Collection findPrimaryKeysByQuery(java.lang.String query, java.lang.Class userObjectClass) throws java.lang.Exception
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.
query
- User SQL query.userObjectClass
- The user object class type (ex. HashMap.class
gives HashMap class type).java.lang.Exception
- if any databse problems in finding the primary
keys or executing the query.findPrimaryKeysByAttributes(AttrValMap,Class)
,
findAllPrimaryKeys(Class)
public java.util.Collection findAllPrimaryKeys(java.lang.Class userObjectClass) throws java.lang.Exception
Assumptions:
An OR mapping exists for this userObjectClass in mapping file.
userObjectClass
- The user object class type (ex. HashMap.class
gives HashMap class type).java.lang.Exception
- if any databse problems in finding the primary
keys or executing the query.findPrimaryKeysByAttributes(AttrValMap,Class)
,
findPrimaryKeysByQuery(String,Class)
public void beginTransaction() throws java.lang.Exception
java.lang.Exception
- Thrown if the thread is already associated
with a transaction or no available resource.isActiveTransaction()
,
commitTransaction()
,
rollbackTransaction()
public boolean isActiveTransaction()
beginTransaction()
,
commitTransaction()
,
rollbackTransaction()
public void commitTransaction() throws java.lang.Exception
java.lang.Exception
- Thrown if the thread is not associated with a
transaction or any databse problems during database
commit.rollbackTransaction()
,
beginTransaction()
,
isActiveTransaction()
public void rollbackTransaction() throws java.lang.Exception
java.lang.Exception
- Thrown if the thread is not associated with a
transaction or any databse problems during database
rollback.commitTransaction()
,
beginTransaction()
,
isActiveTransaction()
public java.sql.ResultSet executeQuery(java.lang.String query) throws java.lang.Exception
query
- typically this is a static SQL SELECT statement.java.lang.Exception
- if a database error occurs.Statement.executeQuery(String)
public int executeUpdate(java.lang.String query) throws java.lang.Exception
query
- an SQL INSERT, UPDATE or DELETE statement or an
SQL statement that returns nothingjava.lang.Exception
- if a database error occurs.Statement.executeUpdate(String)
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |