Updated documentation in Scenarios class + uppdated README.md

Did some method renaming and refactoring

Author: bwajtr

README.md

@@ -1,4 +1,5 @@
 # Java repository layer frameworks comparison
+
 Comparison of usage of non-JPA SQL mapping frameworks for Java (Jooq, Spring JDBCTemplate etc.).
 
 We are not comparing performance (that'll be maybe added later), but rather how are these frameworks used for everyday tasks.
@@ -15,39 +16,36 @@ We tried to find optimal (== most readable) implementation in every framework, b
 ## Scenarios implemented
 
 These are the scenarios:
+
 1. Fetch single entity based on primary key
 2. Fetch list of entities based on condition
 3. Save new single entity and return primary key
 4. Batch insert multiple entities of same type and return generated keys
 5. Update single existing entity - update all fields of entity at once
-6. Fetch entity and it's many-to-one relation (Company for Department)
-7. Fetch entity and it's one-to-many relation (Departments for Company)
-8. Update entities one-to-many relation - add two items, update two items and delete one item
+6. Fetch many-to-one relation (Company for Department)
+7. Fetch one-to-many relation (Departments for Company)
+8. Update entities one-to-many relation (Departments in Company) - add two items, update two items and delete one item - all at once
 9. Complex select - construct select where conditions based on some boolean conditions + throw in some joins
 10. Call stored procedure/function and process results
 11. Execute query using JDBC simple Statement (not PreparedStatement)
 
-See javadoc of [Scenarios](src/main/java/com/clevergang/dbtests/Scenarios.java) class for description of each scenario.
+Each scenario has it's implementation in the Scenarios class. See javadoc of [Scenarios](src/main/java/com/clevergang/dbtests/Scenarios.java) methods for more detailed description of each scenario.
 
 ## Model used
 
 ![Simple company database model](/SimpleCompanyModel.png?raw=true "Simple company database model")
 
 ## Why only non-JPA?
-Well, we were trying to "stick with standard" in our projects so we used JPA in the past, but after many years of JPA usage
-(Hibernate mostly), we realized it's counterproductive. In most of our projects it caused more problems than
-it helped to solve - especially in big projects (with lots of tables and relations).
-There are many reasons of those failures - but the biggest issue is that JPA implementations simply turned into bloatware.
-Lot of strange magic is happening inside and the complexity is so high, that you need a high-class Hibernate uberexpert
-in every team so the app actually shows some performance and the code is manageable...
-
-So we dropped JPA completely, started using JDBCTemplate and discovered that we can deliver apps sooner
-(which was kind of surprising), they are a lot faster (thanks to effective use of DB) and much more robust...
-This was really relaxing and we do not plan to return to JPA at all... (yes, even for CRUD applications!)
-
-This project aims to explore other options in the SQL mapping area than just JDBCTemplate. It should serve us 
+
+Well, we were trying to "stick with standard" in our projects so we used JPA in the past, but after many years of JPA usage (Hibernate mostly), we realized it's counterproductive. In most of our projects it caused more problems than it helped to solve - especially in big projects (with lots of tables and relations). There are many reasons of those failures - but the biggest issue is that JPA implementations simply turned into bloatware. Lot of strange magic is happening inside and the complexity is so high, that you need a high-class Hibernate uberexpert in every team so the app actually shows some performance and the code is manageable...
+
+So we dropped JPA completely, started using JDBCTemplate and discovered that we can deliver apps sooner (which was kind of surprising), they are a lot faster (thanks to effective use of DB) and much more robust... This was really relaxing and we do not plan to return to JPA at all... (yes, even for CRUD applications!) 
+
+This project aims to explore other options in the SQL mapping area than just JDBCTemplate. It should serve us
+ 
 - as point of reference when deciding for SQL mapping framework 
 - as a template of common DB usage scenarios
 - to document best practices of such common usages (**comments are welcomed!**)
 
-Use code in the repository as you like (MIT License)
+
+**Use code in the repository as you like (MIT License)**

dbscenarios.txt

@@ -1,7 +1,7 @@
 package com.clevergang.dbtests;
 
-import com.clevergang.dbtests.repository.api.data.*;
 import com.clevergang.dbtests.repository.api.DataRepository;
+import com.clevergang.dbtests.repository.api.data.*;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.RandomStringUtils;
 import org.slf4j.Logger;
@@ -27,32 +27,41 @@
 public class Scenarios {
     private static final Logger logger = LoggerFactory.getLogger(Scenarios.class);
 
-    private DataRepository repository;
+    private final DataRepository repository;
 
     public Scenarios(DataRepository repository) {
         this.repository = repository;
     }
 
     /**
-     * Load single entity based on primary key
+     * 1. Fetch single entity based on primary key
+     * <br/>
+     * This is the case when pid comes from outside (typically from UI) and we need to fetch complete record from database.
+     *
+     * @param companyPid Primary key of the record coming from outside
      */
-    public void scenarioOne() {
-        Integer pid = 1;
-        repository.findCompany(pid);
+    public void fetchSingleEntityScenario(Integer companyPid) {
+        Company company = repository.findCompany(companyPid);
+
+        logger.info("Fetched result: {}", company);
     }
 
     /**
-     * Load list of entities based on condition
+     * 2. Fetch list of entities based on condition
+     * <br/>
+     * This is a case when we want to get records from database using some kind of filter. Filter values typically come from UI.
+     * @param employeeMinSalary Example of external filter value
      */
-    public void scenarioTwo() {
-        Integer minSalary = 2000;
-        repository.employeesWithSalaryGreaterThan(minSalary);
+    public void fetchListOfEntitiesScenario(Integer employeeMinSalary) {
+        List<Employee> employees = repository.employeesWithSalaryGreaterThan(employeeMinSalary);
+
+        logger.info("Fetched result: {}", employees);
     }
 
     /**
-     * Save new single entity and return primary key
+     * 3. Save new single entity and return primary key
      */
-    public void scenarioThree() {
+    public void saveNewEntityScenario() {
         Project project = new Project();
         project.setName("TestProject");
         project.setDate(LocalDate.now());
@@ -61,9 +70,15 @@ public void scenarioThree() {
     }
 
     /**
-     * Batch insertProject multiple entities of same type and return generated keys
+     * 4. Batch insert multiple entities of same type and return generated keys
+     * <br/>
+     * This scenario represents a situation, when business method, as a result of it's execution, wants to store
+     * multiple records of same type into database effectively.
+     * </br>
+     * In our scenario method, we create 1000 products first and then we want to store them into the database
+     * as fast as we can - through batch insert functionality.
      */
-    public void scenarioFour() {
+    public void batchInsertMultipleEntitiesScenario() {
         // create a list of thousand products
         List<Project> projects = new ArrayList<>();
         StopWatch watch = new StopWatch();
@@ -80,28 +95,37 @@ public void scenarioFour() {
     }
 
     /**
-     * Update single existing entity - update all fields of entity at once
+     * 5. Update single existing entity - update all fields of entity at once
+     * <br/>
+     * This scenario covers typical situation in information systems where a detail of a record is displayed in UI, user
+     * has possibility to modify any field of the record and then he/she presses Save button -> complete record data are sent
+     * back to server and the record should be updated in database.
      */
-    public void scenarioFive() {
-        // Complete already store entity with all fields set - imagine that this object comes from UI edit dialog,
-        // which is typical scenario
+    public void updateCompleteEntityScenario() {
+        // Imagine that this object comes from UI edit dialog, which is typical scenario
+        Employee employeeToUpdate = performSomeEmployeeRecordUpdateInUI();
+
+        // SCENARIO CODE STARTS HERE - update the employee in DB
+
+        repository.updateEmployee(employeeToUpdate);
+
+    }
+
+    private Employee performSomeEmployeeRecordUpdateInUI() {
         Employee employeeToUpdate = new Employee();
         employeeToUpdate.setPid(1);
         employeeToUpdate.setDepartmentPid(1);
         employeeToUpdate.setName("Curt");
         employeeToUpdate.setSurname("Odegaard");
         employeeToUpdate.setEmail("curt.odegaard@updated.com");  // <-- this is updated value
         employeeToUpdate.setSalary(new BigDecimal("15000")); // <-- this is updated value
-
-        // now update the employee in DB
-        repository.updateEmployee(employeeToUpdate);
-
+        return employeeToUpdate;
     }
 
     /**
-     * Fetch many-to-one relation (Company for Department)
+     * 6. Fetch many-to-one relation (Company for Department)
      */
-    public void scenarioSix() {
+    public void fetchManyToOneRelationScenario() {
         Department softwareDevelopmentDepartment = repository.findDepartment(3);
 
         // Getting Company for Department (many-to-one relation) in JPA is quite easy. You typically have
@@ -115,9 +139,9 @@ public void scenarioSix() {
     }
 
     /**
-     * Fetch one-to-many relation (Departments for Company)
+     * 7. Fetch one-to-many relation (Departments for Company)
      */
-    public void scenarioSeven() {
+    public void fetchOneToManyRelationScenario() {
         Company company = repository.findCompany(1);
 
         // For one-to-many relations the situation is quite similar to many-to-one relations (scenario six). In JPA this
@@ -131,7 +155,7 @@ public void scenarioSeven() {
     }
 
     /**
-     * Update one-to-many relation (Departments in Company) at once - add two items, update one items and delete one item.
+     * 8. Update entities one-to-many relation (Departments in Company) - add two items, update two items and delete one item - all at once
      * <br/>
      * This scenario covers situation where we have no idea what operations were performed by the user. We only
      * have new list of Departments and we have to efficiently update DB so it exactly reflects new Departments list.
@@ -141,7 +165,7 @@ public void scenarioSeven() {
      * which were only updated have some additional relations in the database? -> if we delete them, we will delete also those relations ->
      * always ask yourself if this is something you want (or you want risk).
      */
-    public void scenarioEight() {
+    public void updateCompleteOneToManyRelationScenario() {
         Company company = repository.findCompany(1); // Clevergang company
 
         // this call simulates what typically happens in UI - the user chooses new list of departments for company
@@ -150,6 +174,9 @@ public void scenarioEight() {
         // ones were updated - the business service has to determine these changes - which is what rest of the code in this method does
         List<Department> newDepartments = createNewDepartmentsList(company);
 
+
+        // SCENARIO CODE STARTS HERE - update departments in DB
+
         updateDepartments(company, newDepartments);
 
         // now check the results
@@ -190,7 +217,7 @@ private List<Department> createNewDepartmentsList(Company company) {
         // delete one item
         departments.removeIf(department -> department.getName().equals("Lazy Department"));
 
-        // add two items (notice they don't have thier own pid yet)
+        // add two items (notice they don't have their own pid yet)
         departments.add(new Department(company.getPid(), "New department 1"));
         departments.add(new Department(company.getPid(), "New department 2"));
 
@@ -208,41 +235,41 @@ private List<Department> createNewDepartmentsList(Company company) {
 
 
     /**
-     * Execute complex query
-     *
-     * In our case we are executing following query:
-     * Query: get all projects, where the total cost of the project per month is greater than 70000. In the same resultset
+     * 9. Complex select - construct select where conditions based on some boolean conditions + throw in some joins
+     * <br/>
+     * In our case we are executing following query:<br/>
+     * Query: get all projects, where the total cost of the project per month is greater than 70000. In the same result set
      * get all companies participating on such project along with cost of the project for the company.
      */
-    public void scenarioNine() {
+    public void executeComplexSelectScenario() {
         List<ProjectsWithCostsGreaterThanOutput> projectsWithCostsGreaterThan = repository.getProjectsWithCostsGreaterThan(70000);
 
-        logger.info("scenarioNine output: {}", projectsWithCostsGreaterThan);
+        logger.info("executeComplexSelectScenario output: {}", projectsWithCostsGreaterThan);
     }
 
     /**
-     * Execute stored procedure/function and process results
+     * 10. Call stored procedure/function and process results
      */
-    public void scenarioTen() {
+    public void callStoredProcedureScenario() {
         RegisterEmployeeOutput output = repository.callRegisterEmployee("Bretislav", "Wajtr", "bretislav.wajtr@test.com", new BigDecimal(40000), "MyDepartment", "MyCompany");
 
-        logger.info("scenarioTen output: {}", output);
+        logger.info("callStoredProcedureScenario output: {}", output);
     }
 
 
     /**
-     * Execute query using JDBC simple Statement (not PreparedStatement)
-     *
+     * 11. Execute query using JDBC simple Statement (not PreparedStatement)
+     * <br/>
      * Motivation why we need the "static statement" feature: In 96% of the cases, you’re better off writing
      * a PreparedStatement rather than a static statement - it's safer (sql injection),
      * easier (complex data types like dates) and sometimes faster (prepared statements reuse). However, there are
      * edge cases for complex queries and lot of data where it's actually faster to use simple statement query, because
      * your database’s cost-based optimiser or planner obtains some heads-up about what kind of data is really going to
      * be affected by the query and can therefore execute the query faster.
-     *
+     * <p>
      * Good SQL API framework should offer way how to execute simple static statements.
      */
-    public void scenarioEleven() {
+    public void executeSimpleStaticStatementScenario() {
         Company output = repository.findCompanyUsingSimpleStaticStatement(1);
 
         logger.info("Output: {}", output);

src/main/java/com/clevergang/dbtests/Scenarios.java

@@ -30,57 +30,57 @@ public void setup() {
 
     @Test
     public void scenarioOne() {
-        scenarios.scenarioOne();
+        scenarios.fetchSingleEntityScenario(1);
     }
 
     @Test
     public void scenarioTwo() {
-        scenarios.scenarioTwo();
+        scenarios.fetchListOfEntitiesScenario(2000);
     }
 
     @Test
     public void scenarioThree() {
-        scenarios.scenarioThree();
+        scenarios.saveNewEntityScenario();
     }
 
     @Test
     public void scenarioFour() {
-        scenarios.scenarioFour();
+        scenarios.batchInsertMultipleEntitiesScenario();
     }
 
     @Test
     public void scenarioFive() {
-        scenarios.scenarioFive();
+        scenarios.updateCompleteEntityScenario();
     }
 
     @Test
     public void scenarioSix() {
-        scenarios.scenarioSix();
+        scenarios.fetchManyToOneRelationScenario();
     }
 
     @Test
     public void scenarioSeven() {
-        scenarios.scenarioSeven();
+        scenarios.fetchOneToManyRelationScenario();
     }
 
     @Test
     public void scenarioEight() {
-        scenarios.scenarioEight();
+        scenarios.updateCompleteOneToManyRelationScenario();
     }
 
     @Test
     public void scenarioNine() {
-        scenarios.scenarioNine();
+        scenarios.executeComplexSelectScenario();
     }
 
     @Test
     public void scenarioTen() {
-        scenarios.scenarioTen();
+        scenarios.callStoredProcedureScenario();
     }
 
     @Test
     public void scenarioEleven() {
-        scenarios.scenarioEleven();
+        scenarios.executeSimpleStaticStatementScenario();
     }
 
 }