Added proper javadoc to DataRepository interface and moved getProjectsWithCostsUsingNativeQuery.sql under jooq/queries directory to indicate that this file is used only by jOOQ implementation.

Author: bretislav.wajtr

src/main/java/com/clevergang/dbtests/repository/api/DataRepository.java

@@ -14,52 +14,131 @@
  */
 public interface DataRepository {
 
-    // companies
+    // Companies
 
+    /**
+     * @param pid Primary key of the company record to be found
+     * @return Should return full record of the Company record identified by pid
+     */
     Company findCompany(Integer pid);
 
+    /**
+     * @param pid Primary key of the company record to be found
+     * @return Should return full record of the Company record identified by pid. A static (non-prepared) statement should be used for that.
+     */
     Company findCompanyUsingSimpleStaticStatement(Integer pid);
 
-    // departments
 
+
+    // Departments
+
+    /**
+     * @param pid Primary key of the Department record to be found
+     * @return Should return full record of the Department record identified by pid
+     */
     Department findDepartment(Integer pid);
 
+    /**
+     * Should return full records of all Departments assigned to the Company (passed in as parameter).
+     * @param company Full Company record
+     * @return List of Departments
+     */
     List<Department> findDepartmentsOfCompany(Company company);
 
+    /**
+     * Should immediately delete Departments passed in as parameter from database. Should do it in most efficient way (preferably as batch operation).
+     * We expect that the deletions were already performed in database upon return from this method.
+     *
+     * @param departmentsToDelete Full records of Departments to be deleted
+     */
     void deleteDepartments(List<Department> departmentsToDelete);
 
+    /**
+     * Should immediately update Department records passed in as parameter. Should do it in most efficient way (preferably as batch operation).
+     * We expect that the updates were already performed in database upon return from this method (meaning all required SQL statements were already
+     * executed and are not deferred to a later time).
+     *
+     * @param departmentsToUpdate Full records of Departments to be updated. Update all fields of Department, identified by Department.getPid()
+     */
     void updateDepartments(List<Department> departmentsToUpdate);
 
+    /**
+     * Should immediately insert Department records passed in as parameter. Should do it in most efficient way (preferably as batch operation).
+     * We expect that the inserts were already performed in database upon return from this method (meaning all required SQL statements were already
+     * executed and are not deferred to a later time).
+     *
+     * @param departmentsToInsert Full records of Departments to be inserted. Records should have getPid()==null
+     */
     void insertDepartments(List<Department> departmentsToInsert);
 
-    // projects
+
+
+
+    // Projects
 
     /**
      * Insert project and return PID of newly created item
+     *
      * @param project Project to be inserted
      * @return PID of new record in database
      */
     Integer insertProject(Project project);
 
     /**
-     * Insert projects and return all PIDs of newly created records.
+     * Should immediately insert Project records passed in as parameter. Should do it in most efficient way (preferably as batch operation).
+     * We expect that the inserts were already performed in database upon return from this method (meaning all required SQL statements were already
+     * executed and are not deferred to a later time).
+     *
      * @param projects New projects to insert
      * @return List of PIDs of newly created records.
      */
     List<Integer> insertProjects(List<Project> projects);
 
+    /**
+     * Execute following query: get all projects, where the total cost of the project per month is greater than parameter totalCostBoundary. In the same result set
+     * get all companies participating on such project along with cost of the project for the company.
+     */
     List<ProjectsWithCostsGreaterThanOutput> getProjectsWithCostsGreaterThan(int totalCostBoundary);
 
-    // employees
 
+
+    // Employees
+
+    /**
+     * @param pid Primary key of the employee record to be found
+     * @return Should return full record of the Employee record identified by pid
+     */
     Employee findEmployee(Integer pid);
 
+
+    /**
+     * Execute following query and return all Employee records satisfying following condition: salary of the employee
+     * is greater than parameter minSalary
+     */
     List<Employee> employeesWithSalaryGreaterThan(Integer minSalary);
 
+
+    /**
+     * Should immediately update Employee record passed in as parameter. Should do it in most efficient way.
+     * We expect that the update was already performed in database upon return from this method (meaning SQL statement was already
+     * executed and is not deferred to a later time).
+     *
+     * @param employeeToUpdate Full records of Employee to be updated. Update all fields of Employee, identified by Employee.getPid()
+     */
     void updateEmployee(Employee employeeToUpdate);
 
+
+    /**
+     * Register new employee and create company and department if required - use stored procedure register_employee (see register_employee.sql)
+     * to perform the operation.
+     *
+     * @return Newly created PIDs of records (output of the stored procedure)
+     */
     RegisterEmployeeOutput callRegisterEmployee(String name, String surname, String email, BigDecimal salary,
                                                 String departmentName, String companyName);
 
+    /**
+     * @return Return count of records in Project table
+     */
     Integer getProjectsCount();
 }

src/main/java/com/clevergang/dbtests/repository/impl/jooq/JooqDataRepositoryImpl.java

@@ -211,7 +211,7 @@ public Integer getProjectsCount() {
 
     private List<ProjectsWithCostsGreaterThanOutput> getProjectsWithCostsUsingNativeQuery(int totalCostBoundary) {
         // FIXME: We should cache loaded scripts in real production code!
-        String query = loadSQLScript("queries/getProjectsWithCostsUsingNativeQuery.sql");
+        String query = loadSQLScript("jooq/queries/getProjectsWithCostsUsingNativeQuery.sql");
 
         return create
                 .resultQuery(query, totalCostBoundary)