javadoc updates

[utils] / test / enterprise / src / main / java / org / wamblee / support / persistence / DatabaseUtils.java

diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java
index b57cd46184e3c4293da6ca5e25c01f6aec8957cd..07dbca0f64363988f18c76da9bd599ba55ee2865 100644 (file)
--- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java
+++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseUtils.java
@@ -45,15 +45,44 @@ import org.dbunit.operation.DatabaseOperation;
  */
 public class DatabaseUtils {
 
+    /**
+     * Represents a set of tables.
+     *  
+     * @author Erik Brakkee
+     */
     public static interface TableSet {
         boolean contains(String aTableName);
     }
 
+    /**
+     * Represents a unit of work (transaction).
+     * 
+     * @author Erik Brakkee
+     *
+     * @param <T> Type of return value. 
+     */
     public static interface JdbcUnitOfWork<T> {
+        /**
+         * Executes statement within a transaction. 
+         * @param aConnection Connection. 
+         * @return Result of the work. 
+         * @throws Exception
+         */
         T execute(Connection aConnection) throws Exception;
     }
 
+    /**
+     * Operation to be executed on a set of tables for each table 
+     * individually. 
+     * 
+     * @author Erik Brakkee
+     */
     public static interface TableSetOperation {
+        /**
+         * Executes on a table. 
+         * @param aTable Table name. 
+         * @throws Exception
+         */
         void execute(String aTable) throws Exception;
     }
 
@@ -108,10 +137,22 @@ public class DatabaseUtils {
         connections.clear();
     }
 
+    /**
+     * Creates database tester. 
+     * @param aTables Tables to create the tester for. 
+     * @return Database tester. 
+     * @throws Exception
+     */
     public IDatabaseTester createDbTester(ITableFilterSimple aTables) throws Exception {
         return createDbTester(getTableNames(aTables));
     }
-
+    
+    /**
+     * Creates database tester. 
+     * @param aTables Tables to create the tester for. 
+     * @return Database tester. 
+     * @throws Exception
+     */
     public IDatabaseTester createDbTester(String[] aTables) throws Exception {
         IDatabaseConnection connection = dbtester.getConnection();
         connections.add(connection);
@@ -119,6 +160,12 @@ public class DatabaseUtils {
         return dbtester;
     }
 
+    /**
+     * Executes an operation on a set of tables. 
+     * @param aTables Tables. 
+     * @param aOperation Operation. 
+     * @throws Exception
+     */
     public void executeOnTables(ITableFilterSimple aTables,
         final TableSetOperation aOperation) throws Exception {
         final String[] tableNames = getTableNames(aTables);
@@ -132,6 +179,12 @@ public class DatabaseUtils {
         });
     }
 
+    /**
+     * Cleans a number of database tables. This means deleting the content not dropping the tables. 
+     * This may fail in case of cyclic dependencies between the tables (current limitation). 
+     * @param aSelection Tables.
+     * @throws Exception
+     */
     public void cleanDatabase(ITableFilterSimple aSelection) throws Exception {
 
         final String[] tableNames = getTableNames(aSelection);
@@ -151,12 +204,19 @@ public class DatabaseUtils {
 
     }
 
-    public <T> T executeInTransaction(JdbcUnitOfWork<T> aCallback)
+    /**
+     * Executes a unit of work within a transaction. 
+     * @param <T> Result type of th ework. 
+     * @param aWork Unit of work. 
+     * @return
+     * @throws Exception
+     */
+    public <T> T executeInTransaction(JdbcUnitOfWork<T> aWork)
         throws Exception {
         Connection connection = dataSource.getConnection();
         connection.setAutoCommit(false);
         try {
-            T value = aCallback.execute(connection);
+            T value = aWork.execute(connection);
             connection.commit();
             return value;
         } finally {
@@ -165,7 +225,10 @@ public class DatabaseUtils {
     }
     
     /**
-     * @throws SQLException
+     * Returns table names based on a table filter. 
+     * @param aSelection Table filter. 
+     * @return Table names. 
+     * @throws Exception
      */
     public String[] getTableNames(ITableFilterSimple aSelection)
         throws Exception {
@@ -191,9 +254,9 @@ public class DatabaseUtils {
     }
 
     /**
-     * @return
-     * @throws SQLException
+     * Use {@link #cleanDatabase(ITableFilterSimple)} instead. 
      */
+    @Deprecated
     public void emptyTables(final ITableFilterSimple aSelection)
         throws Exception {
         executeOnTables(aSelection, new TableSetOperation() {
@@ -204,13 +267,18 @@ public class DatabaseUtils {
     }
 
     /**
-     * @return
-     * @throws SQLException
+     * User {@link #cleanDatabase(ITableFilterSimple)} instead. 
      */
+    @Deprecated
     public void emptyTable(String aTable) throws Exception {
         executeSql("delete from " + aTable);
     }
 
+    /**
+     * Drops tables. This only works if there are no cyclic dependencies between the tables. 
+     * @param aTables Tables to drop. 
+     * @throws Exception
+     */
     public void dropTables(ITableFilterSimple aTables) throws Exception {
         final String[] tableNames = getTableNames(aTables);
         String[] sortedTables = executeInTransaction(new JdbcUnitOfWork<String[]>() {
@@ -231,8 +299,9 @@ public class DatabaseUtils {
     }
 
     /**
-     * @return
-     * @throws SQLException
+     * Drops a table. 
+     * @param aTable Table to drop. 
+     * @throws Exception
      */
     public void dropTable(final String aTable) throws Exception {
         executeInTransaction(new JdbcUnitOfWork<Void>() {
@@ -343,6 +412,13 @@ public class DatabaseUtils {
         }
     }
 
+    /**
+     * Executes an update. 
+     * @param aConnection Connection to use. 
+     * @param aSql SQL update to use. 
+     * @param aArgs Arguments to the update. 
+     * @return Number of rows updated. 
+     */
     public int executeUpdate(Connection aConnection, final String aSql,
         final Object... aArgs) {
         try {
@@ -400,7 +476,9 @@ public class DatabaseUtils {
     }
 
     /**
-     * @return
+     * Gets the table size. 
+     * @param aTable Table. 
+     * @return Table size. 
      * @throws SQLException
      */
     public int getTableSize(final String aTable) throws Exception {
@@ -415,6 +493,12 @@ public class DatabaseUtils {
 
     }
 
+    /**
+     * Counts the results in a result set. 
+     * @param aResultSet Resultset. 
+     * @return Number of rows in the set. 
+     * @throws SQLException
+     */
     public int countResultSet(ResultSet aResultSet) throws SQLException {
         int count = 0;