DataSourceDAO¶
-
public abstract class
DataSourceDAO
implements DAO¶ The abstract DataSourceDAO class encapsulates a DataSourceDAOFactory object. It basically provides methods, such as getTransaction() and createTransaction(), for any subclasses to get or create a transaction for accessing the underlying data source. It also provides some convenient methods for the subclasses to access, like querying and updating, the data source.
When using the convenient methods, some basic parameters need to be defined. The parameters should be stored in the Properties object which can be retrieved by calling getProperties().
The key-value pairs of the parameters must be in the following format:
Key Value Used by finder:key The key finder SQL statement findByKey() finder: {alias name} The finder SQL statement find() column: {name in the data source} The column’s key in the DVO getColumnCodeName(), executeQuery() sql: {alias name} The SQL statement getSQL(), update() Author: Hugo Y. K. Lam
Methods¶
create¶
-
public void
create
(DVO data)¶ Creates the given value object in the data source.
Parameters: - data – the value object.
Throws: - DAOException – if unable to create the data.
- ClassCastException – if the value object is not DataSourceDVO.
See also:
hk.hku.cecid.piazza.commons.dao.DAO.create(hk.hku.cecid.piazza.commons.dao.DVO)
createTransaction¶
-
protected DataSourceTransaction
createTransaction
()¶ Creates a new DataSourceTransaction object from the underlying data source factory.
Throws: - DAOException – if unable to create the transaction.
Returns: a new DataSourceTransaction object.
executeQuery¶
-
protected List
executeQuery
(String sql)¶ Executes a SQL query on the data source and returns a List of DVO which matches.
Parameters: - sql – the SQL query statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeQuery¶
-
protected List
executeQuery
(DataSourceTransaction tx, String sql)¶ Executes a SQL query on the data source and returns a List of DVO which matches.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL query statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeQuery¶
-
protected List
executeQuery
(String sql, Object[] paras)¶ Executes a SQL query on the data source and returns a List of DVO which matches.
Parameters: - sql – the SQL query statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeQuery¶
-
protected List
executeQuery
(DataSourceTransaction tx, String sql, Object[] paras)¶ Executes a SQL query on the data source and returns a List of DVO which matches.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL query statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeRawQuery¶
-
protected List
executeRawQuery
(String sql, Object[] paras)¶ Executes a SQL query on the data source and returns a List of raw data which matches.
Parameters: - sql – the SQL query statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeRawQuery¶
-
protected List
executeRawQuery
(DataSourceTransaction tx, String sql, Object[] paras)¶ Executes a SQL query on the data source and returns a List of raw data which matches.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL query statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO resulted from the specified SQL query. An empty List will be returned if there is no matching data.
executeUpdate¶
-
protected int
executeUpdate
(String sql)¶ Executes a SQL update on the data source and returns an integer indicating the update result.
Parameters: - sql – the SQL update statement.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an integer indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate().
executeUpdate¶
-
protected int
executeUpdate
(DataSourceTransaction tx, String sql)¶ Executes a SQL update on the data source and returns an integer indicating the update result.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL update statement.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an integer indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate().
executeUpdate¶
-
protected int
executeUpdate
(String sql, Object[] paras)¶ Executes a SQL update on the data source and returns an integer indicating the update result.
Parameters: - sql – the SQL update statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an integer indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate().
executeUpdate¶
-
protected int
executeUpdate
(DataSourceTransaction tx, String sql, Object[] paras)¶ Executes a SQL update on the data source and returns an integer indicating the update result.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL update statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an integer indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate()
executeUpdate¶
-
protected int[]
executeUpdate
(String sql, Object[][] paras)¶ Executes a SQL update on the data source and returns an array of integers indicating the update results.
Parameters: - sql – the SQL update statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement and multiple sets if it is a batch update.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an array of integers indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate().
executeUpdate¶
-
protected int[]
executeUpdate
(DataSourceTransaction tx, String sql, Object[][] paras)¶ Executes a SQL update on the data source and returns an array of integers indicating the update results.
Parameters: - tx – the DataSourceTransaction to be used in execution.
- sql – the SQL update statement.
- paras – the parameter values used by the specified SQL statement. The number, format, and sequence of the parameter values should match the statement. null if there is no parameter for the statement and multiple sets if it is a batch update.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an array of integers indicating the update results. Same as the value returned by java.sql.Statement.executeUpdate().
find¶
-
protected List
find
(String finder, Object[] paras)¶ Retrieves data from the data source as a List of DVO by searching with the specified data values.
Parameters: - finder – the name of the finder SQL statement.
- paras – the parameter values used by the finder statement.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a List of DVO found by the specified data values. An empty List will be returned if there is no matching data.
findByKey¶
-
protected DVO
findByKey
(Object[] keys)¶ Retrieves data from the data source by searching with the specified key values.
Parameters: - keys – the key values for querying the data source.
Throws: - DAOException – if errors found when retrieving data from the data source.
Returns: a DVO found by the specified key values. If there are more than one DVO found, the first one will be returned. null will be returned if nothing was found.
getColumnCodeName¶
getFactory¶
-
public DAOFactory
getFactory
()¶ Gets the DAO factory of this DAO.
Returns: the DAO factory.
getFilter¶
getFinder¶
getOrder¶
getParameters¶
-
public Properties
getParameters
()¶ Gets the parameters of this DAO.
Returns: a Properties which stored the parameters for this DAO.
getSQL¶
getTransaction¶
-
public Transaction
getTransaction
()¶ Gets the transaction of this DAO. This method returns null if this DAO is not under a transaction.
Throws: - DAOException – if unable to get the transaction.
Returns: the transaction of this DAO.
See also:
hk.hku.cecid.piazza.commons.dao.DAO.getTransaction()
getTransaction¶
-
protected DataSourceTransaction
getTransaction
(boolean create)¶ Gets the transaction of this DAO. This method returns a new transaction if and only if this DAO is not under a transaction and the create parameter is set to true. Notice that a newly created transaction will not be set as the transaction of this DAO. It is only created for convenience of use.
Parameters: - create – true if a new transaction should be created if this DAO is not under a transaction.
Throws: - DAOException – if unable get or create a transaction.
Returns: the transaction of this DAO or a new transaction.
isUnderTransaction¶
-
public boolean
isUnderTransaction
()¶ Checks if this DAO is under a transaction.
Returns: true if this DAO is under a transaction.
persist¶
-
public boolean
persist
(DVO data)¶ Persists the given value object to the data source.
Parameters: - data – the value object.
Throws: - DAOException – if unable to persist the data.
- ClassCastException – if the DAO data is not DataSourceDVO.
Returns: true if the data is found and persisted.
See also:
hk.hku.cecid.piazza.commons.dao.DAO.persist(hk.hku.cecid.piazza.commons.dao.DVO)
remove¶
-
public boolean
remove
(DVO data)¶ Removes the given value object from the data source.
Parameters: - data – the value object.
Throws: - DAOException – if unable to remove the data.
- ClassCastException – if the value object is not DataSourceDVO.
Returns: true if the data is found and removed.
See also:
hk.hku.cecid.piazza.commons.dao.DAO.remove(hk.hku.cecid.piazza.commons.dao.DVO)
retrieve¶
-
public boolean
retrieve
(DVO data)¶ Retrieves the given value object from the data source.
Parameters: - data – the value object.
Throws: - DAOException – if unable to retrieve the data.
- ClassCastException – if the value object is not DataSourceDVO.
Returns: true if the data is found and retrieved.
See also:
hk.hku.cecid.piazza.commons.dao.DAO.retrieve(hk.hku.cecid.piazza.commons.dao.DVO)
setFactory¶
-
void
setFactory
(DataSourceDAOFactory factory)¶ Sets the DAO factory of this DAO.
Parameters: - factory – the DAO factory.
setTransaction¶
-
public void
setTransaction
(Transaction tx)¶ Sets the transaction of this DAO.
Parameters: - tx – the transaction of this DAO.
Throws: - DAOException – if the given transaction is not supported.
update¶
-
protected int
update
(String sqlname, Object[] paras)¶ Updates the data source with the specified data values.
Parameters: - sqlname – the name of the SQL statement to be used.
- paras – the data values to be updated to the data source.
Throws: - DAOException – if errors found when updating data to the data source.
Returns: an integer indicating the update result. Same as the value returned by java.sql.Statement.executeUpdate()