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

Constructors

DataSourceDAO

protected DataSourceDAO()

Creates a new instance of DataSourceDAO.

Methods

create

public void create(DVO data)

Creates the given value object in the data source.

Parameters:
  • data – the value object.
Throws:

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:
Returns:

a new DataSourceTransaction object.

daoCreated

public void daoCreated()

Initializes this DAO.

See also: hk.hku.cecid.piazza.commons.dao.DAO.daoCreated()

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

protected String getColumnCodeName(String name)

Gets the code name of the specified column in the data source.

Parameters:
  • name – the name of the column.
Returns:

the code name of the specified column.

getFactory

public DAOFactory getFactory()

Gets the DAO factory of this DAO.

Returns:the DAO factory.

getFilter

protected String getFilter(String name)

Gets the filter partial SQL statement with the specified name.

Parameters:
  • name – the name which refers to the filter partial SQL statement.
Returns:

the filter partial SQL statement associated with the specified name.

getFinder

protected String getFinder(String name)

Gets the finder SQL statement with the specified name.

Parameters:
  • name – the name which refers to the finder SQL statement.
Returns:

the finder SQL statement associated with the specified name.

getOrder

protected String getOrder(String name)

Gets the order partial SQL statement with the specified name.

Parameters:
  • name – the name which refers to the order partial SQL statement.
Returns:

the order partial SQL statement associated with the specified name.

getParameters

public Properties getParameters()

Gets the parameters of this DAO.

Returns:a Properties which stored the parameters for this DAO.

getSQL

protected String getSQL(String name)

Gets the SQL statement with the specified name.

Parameters:
  • name – the name which refers to the SQL statement.
Returns:

the SQL statement associated with the specified name.

getTransaction

public Transaction getTransaction()

Gets the transaction of this DAO. This method returns null if this DAO is not under a transaction.

Throws:
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:
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:
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:
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:
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()