org.gjt.tw.dbobjects
Class DBManager

java.lang.Object
  |
  +--org.gjt.tw.dbobjects.DBManager

public class DBManager

extends java.lang.Object

DBManager is responsible for the access to the database. It has to be itialized before the first use with a set of properties. Most of its functions are used by StorableObject and don't need to be called by a high level application.

The most important functions are insert, update, and delete for manipulating data stored in the database. Each of these function take an ObjectMapping as argument to identify which table has to be changed using which SQL string.

The methods getByField and getByWhereClause take the name of an object field, or a WHERE clause, respectively, as arguments. They create objects according to the information stored in the ObjectMapping given.

There are two kinds of get-methods: one kind returns arrays of objects. These arrays can be cast directly to an array of the real class of the objects. Use these methods to get lists of objects if you do not save the resulting list for further uses and do not change the number of objects.

The other kind of get-methods return vectors of objects. Use these methods if you are developping an application with single access to a database. Under these circumstances you can read the objects from the database once and add and remove objects during lifetime of your program without further calls to fetch the objects again.

Method Summary

static boolean	delete(ObjectMapping mapping, java.lang.Object[] parameters) Deletes an object that is stored in the database.
static void	destroy() Detroys the connection to the database and gives used resources free.
static StorableObject[]	getAll(ObjectMapping mapping) Retrieves all objects stored in a table of the database and returns an array of objects.
static StorableObject[]	getAll(ObjectMapping mapping, java.lang.String appendedSqlString) Retrieves all objects stored in a table of the database and returns an array of objects.
static java.util.Vector	getAllVector(ObjectMapping mapping) Retrieves all objects stored in a table of the database and returns a vector of all objects..
static java.util.Vector	getAllVector(ObjectMapping mapping, java.lang.String appendedSqlString) Retrieves all objects stored in a table of the database and returns a vector of all objects.
static IBroker	getBroker() Returns the current database connection broker.
static StorableObject[]	getByField(ObjectMapping mapping, java.lang.String fieldName, java.lang.Object fieldContent) Retrieves the objects stored in the database for which a given field corresponds to the content given and returns an array of objects.
static StorableObject[]	getByField(ObjectMapping mapping, java.lang.String fieldName, java.lang.Object fieldContent, java.lang.String appendedSqlString) Retrieves the objects stored in the database for which a given field corresponds to the content given and returns an array of objects.
static java.util.Vector	getByFieldVector(ObjectMapping mapping, java.lang.String fieldName, java.lang.Object fieldContent) Retrieves the objects stored in the database for which a given field corresponds to the content given and returns a vector of all objects.
static java.util.Vector	getByFieldVector(ObjectMapping mapping, java.lang.String fieldName, java.lang.Object fieldContent, java.lang.String appendedSqlString) Retrieves the objects stored in the database for which a given field corresponds to the content given and returns a vector of all objects.
static StorableObject[]	getByWhereClause(ObjectMapping mapping, java.lang.String whereClause) Retrieves the objects stored in the database an SQL SELECT returns given a WHERE clause and returns an array of objects.
static java.util.Vector	getByWhereClauseVector(ObjectMapping mapping, java.lang.String whereClause) Retrieves the objects stored in the database an SQL SELECT returns given a WHERE clause and returns a vector of all objects.
static void	handleException(java.lang.Exception e) This method is called for any exception happened during database access.
static void	init(IBroker broker) init use init if you want to access the initialized variable setBroker can be used instead of init
static long	insert(ObjectMapping mapping, java.lang.Object[] parameters) Executes an SQL INSERT string generated by the object mapping.
static boolean	isInitialized() Checks whether the database manager has already been initialized.
static void	setBroker(IBroker ibroker) Sets the connection broker
static boolean	update(ObjectMapping mapping, java.lang.Object[] parameters) Updates an object that is stored in the database.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setBroker

public static void setBroker(IBroker ibroker)

Sets the connection broker

Parameters:

ibroker - The new broker value

getAll

public static StorableObject[] getAll(ObjectMapping mapping)
                               throws DatabaseException,
                                      ObjectException

Retrieves all objects stored in a table of the database and returns an array of objects. Use this method if you only want to have a list of all objects currently stored in the database and do not want to add or delete objects from this list.

Parameters:

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getAll

public static StorableObject[] getAll(ObjectMapping mapping,
                                      java.lang.String appendedSqlString)
                               throws DatabaseException,
                                      ObjectException

Retrieves all objects stored in a table of the database and returns an array of objects. Use this method if you only want to have a list of all objects currently stored in the database and do not want to add or delete objects from this list.

Parameters:

appendedSqlString - A string that is appended after the where clause. Might contain "order by", "group by", etc statements.

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getAllVector

public static java.util.Vector getAllVector(ObjectMapping mapping)
                                     throws DatabaseException,
                                            ObjectException

Retrieves all objects stored in a table of the database and returns a vector of all objects.. Use this method if you want to keep the resulting objects permanently in memory and add or delete objects.

Parameters:

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getAllVector

public static java.util.Vector getAllVector(ObjectMapping mapping,
                                            java.lang.String appendedSqlString)
                                     throws DatabaseException,
                                            ObjectException

Retrieves all objects stored in a table of the database and returns a vector of all objects. Use this method if you want to keep the resulting objects permanently in memory and add or delete objects.

Parameters:

appendedSqlString - A string that is appended after the where clause. Might contain "order by", "group by", etc statements.

mapping - Description of Parameter

Returns:

Vector A vector of objects of the class indicated by the object mapping.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getBroker

public static IBroker getBroker()

Returns the current database connection broker.

Returns:

the IBroker object

getByField

public static StorableObject[] getByField(ObjectMapping mapping,
                                          java.lang.String fieldName,
                                          java.lang.Object fieldContent)
                                   throws DatabaseException,
                                          ObjectException

Retrieves the objects stored in the database for which a given field corresponds to the content given and returns an array of objects. Use this method if you only want to have a list of all objects currently stored in the database and do not want to add or delete objects from this list.

Parameters:

fieldName - Name of the object's field (not the name of the database column!)

fieldContent - Object containing the value that is searched for. Simple types have to wrapped by their corresponding class. Example: Integer integer = new Integer (i).

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getByField

public static StorableObject[] getByField(ObjectMapping mapping,
                                          java.lang.String fieldName,
                                          java.lang.Object fieldContent,
                                          java.lang.String appendedSqlString)
                                   throws DatabaseException,
                                          ObjectException

Retrieves the objects stored in the database for which a given field corresponds to the content given and returns an array of objects. Use this method if you only want to have a list of all objects currently stored in the database and do not want to add or delete objects from this list.

Parameters:

fieldName - Name of the object's field (not the name of the database column!)

fieldContent - Object containing the value that is searched for. Simple types have to wrapped by their corresponding class. Example: Integer integer = new Integer (i).

appendedSqlString - string appended behind the WHERE clause (e.g. "ORDER BY", etc).

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getByFieldVector

public static java.util.Vector getByFieldVector(ObjectMapping mapping,
                                                java.lang.String fieldName,
                                                java.lang.Object fieldContent)
                                         throws DatabaseException,
                                                ObjectException

Retrieves the objects stored in the database for which a given field corresponds to the content given and returns a vector of all objects. Use this method if you want to keep the resulting objects permanently in memory and add or delete objects.

Parameters:

fieldName - Name of the object's field (not the name of the database column!)

fieldContent - Object containing the value that is searched for. Simple types have to wrapped by their corresponding class. Example: Integer integer = new Integer (i).

mapping - Description of Parameter

Returns:

Vector A vector of objects of the class indicated by the object mapping.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getByFieldVector

public static java.util.Vector getByFieldVector(ObjectMapping mapping,
                                                java.lang.String fieldName,
                                                java.lang.Object fieldContent,
                                                java.lang.String appendedSqlString)
                                         throws DatabaseException,
                                                ObjectException

Retrieves the objects stored in the database for which a given field corresponds to the content given and returns a vector of all objects. Use this method if you want to keep the resulting objects permanently in memory and add or delete objects.

Parameters:

fieldName - Name of the object's field (not the name of the database column!)

fieldContent - Object containing the value that is searched for. Simple types have to wrapped by their corresponding class. Example: Integer integer = new Integer (i).

appendedSqlString - string appended behind the WHERE clause (e.g. "ORDER BY", etc).

mapping - Description of Parameter

Returns:

Vector A vector of objects of the class indicated by the object mapping.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getByWhereClause

public static StorableObject[] getByWhereClause(ObjectMapping mapping,
                                                java.lang.String whereClause)
                                         throws DatabaseException,
                                                ObjectException

Retrieves the objects stored in the database an SQL SELECT returns given a WHERE clause and returns an array of objects. Use this method if you only want to have a list of all objects currently stored in the database and do not want to add or delete objects from this list.

Parameters:

whereClause - The WHERE clause as used by the select SQL string.

mapping - Description of Parameter

Returns:

StorableObject[] An array of objects of the class indicated by the object mapping. The array can be casted directly to the objects' class. In case of no hits null is returned.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

getByWhereClauseVector

public static java.util.Vector getByWhereClauseVector(ObjectMapping mapping,
                                                      java.lang.String whereClause)
                                               throws DatabaseException,
                                                      ObjectException

Retrieves the objects stored in the database an SQL SELECT returns given a WHERE clause and returns a vector of all objects. Use this method if you want to keep the resulting objects permanently in memory and add or delete objects.

Parameters:

whereClause - The WHERE clause as used by the select SQL string.

mapping - Description of Parameter

Returns:

Vector A vector of objects of the class indicated by the object mapping.

Throws:

DatabaseException - Description of Exception

ObjectException - Description of Exception

isInitialized

public static boolean isInitialized()

Checks whether the database manager has already been initialized.

Returns:

true if database connectivity is already established

delete

public static boolean delete(ObjectMapping mapping,
                             java.lang.Object[] parameters)
                      throws DatabaseException

Deletes an object that is stored in the database. This functions is typically only called from within StorableObject. It gets an object mapping containing the SQL DELETE string that is to be used. The array of objects contains all parameters needed for the SQL string to be executed as PreparedStatement.

Parameters:

mapping - The object mapping

parameters - An array of objects used as parameters

Returns:

True if the database was updated successfully, false otherwise

Throws:

DatabaseException - Description of Exception

destroy

public static void destroy()
                    throws DatabaseException

Detroys the connection to the database and gives used resources free. Should be called before termination of the application.

Throws:

DatabaseException - Description of Exception

handleException

public static void handleException(java.lang.Exception e)

This method is called for any exception happened during database access. Depending on the type of exception different actions are done. Default action is to write the exception into the log file.

Parameters:

e - the exception that happened

init

public static void init(IBroker broker)

init use init if you want to access the initialized variable setBroker can be used instead of init

Parameters:

broker - Description of Parameter

insert

public static long insert(ObjectMapping mapping,
                          java.lang.Object[] parameters)
                   throws DatabaseException

Executes an SQL INSERT string generated by the object mapping. If auto_increment is used the generated value (either with MySQL's built-in support or by using the MAX statement) is returned as result. Parameters for the prepared statement are passed in an array of objects.

Parameters:

mapping - the object mapping

parameters - An array of objects used as parameters

Returns:

A long containing the values of the new entry if auto_increment is used; -1 otherwise.

Throws:

DatabaseException - Description of Exception

update

public static boolean update(ObjectMapping mapping,
                             java.lang.Object[] parameters)
                      throws DatabaseException

Updates an object that is stored in the database. This functions is typically only called from within StorableObject. It gets an object mapping containing the SQL UPDATE string that is to be used. The array of objects contains all parameters needed for the SQL string to be executed as PreparedStatement.

Parameters:

mapping - The object mapping

parameters - An array of objects used as parameters

Returns:

True if the database was updated successfully, false otherwise

Throws:

DatabaseException - Description of Exception