Added more docs and demo code alignment

Author: kai-niemi

README.md

@@ -23,8 +23,8 @@ Common Spring Boot features in all demos:
 - Hypermedia API via Spring HATEOAS and HAL media type
 - Simple HTTP client invoking commands
 
-The most documented demo is the JDBC version. It also includes an extra aspect for setting
-transaction attributes including time travel / follower reads.
+The most documented demo is the JDBC version. It includes an extra aspect for setting transaction attributes such 
+as time travel / follower reads. 
 
 ## Prerequisites
 

jdbc/README.md

@@ -1,5 +1,11 @@
 # Roach Demo Data :: JDBC
 
-Spring Boot Demo using CockroachDB with vanilla spring-data-jdbc.
+A CockroachDB Spring Boot Demo using [Spring Data JDBC](https://spring.io/projects/spring-data-jdbc)
+for data access.
+
+Spring Data JDBC provides a simpler, yet powerful model than JPA or any other ORM frameworks. It's considered a good 
+fit for data access logic that doesn't involve large, complex domain model mapping or any of the advanced features 
+of JPA, such as lazy loading, second level caching, auto-batching and transparent persistence.
 
+The JDBC demo has most code comments and also provides a few extra features compared to the other modules.
 

jdbc/pom.xml

@@ -35,12 +35,6 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-actuator</artifactId>
         </dependency>
-<!--
-        <dependency>
-            <groupId>org.springframework.data</groupId>
-            <artifactId>spring-data-commons</artifactId>
-        </dependency>
--->
         <dependency>
             <groupId>org.liquibase</groupId>
             <artifactId>liquibase-core</artifactId>
@@ -58,16 +52,6 @@
             <plugin>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
-<!--
-                <executions>
-                    <execution>
-                        <configuration>
-                            <executable>true</executable>
-                            <mainClass>io.roach.demo.data.JdbcApplication</mainClass>
-                        </configuration>
-                    </execution>
-                </executions>
--->
             </plugin>
         </plugins>
     </build>

jdbc/src/main/java/io/roach/demo/data/JdbcApplication.java

@@ -106,6 +106,9 @@ public static void main(String[] args) {
         testClient();
     }
 
+    /**
+     * Client logic that submits money transfer requests to the REST API.
+     */
     public static void testClient() {
         logger.info("Lets move some $$ around!");
 
@@ -164,6 +167,9 @@ enum AccountType {
     expense
 }
 
+/**
+ * Domain entity mapped to the account table.
+ */
 class Account {
     @Id
     private Long id;
@@ -191,6 +197,9 @@ public BigDecimal getBalance() {
     }
 }
 
+/**
+ * Account resource represented in HAL+JSON via REST API.
+ */
 @Relation(value = "account", collectionRelation = "accounts")
 class AccountModel extends RepresentationModel<AccountModel> {
     private String name;
@@ -225,27 +234,24 @@ public void setBalance(BigDecimal balance) {
 }
 
 /**
- * Pagination is not available in spring-data-jdbc yet so we create a separate
- * repository to provide basic limit+offset pagination of accounts.
+ * Pagination is not available in spring-data-jdbc (yet) so we create a separate
+ * repository to provide basic limit+offset pagination queries for accounts.
  */
 interface PagedAccountRepository {
     Page<Account> findAll(Pageable pageable);
 }
 
 @Repository
 interface PagedAccountHelper extends org.springframework.data.repository.Repository<Account, Long> {
-    /**
-     * Selects a page of accounts using follower reads.
-     */
     @Query("SELECT * FROM account LIMIT :pageSize OFFSET :offset")
     List<Account> findAll(@Param("pageSize") int pageSize, @Param("offset") long offset);
 
-    @Query("SELECT count(id) from account")
+    @Query("SELECT count(id) FROM account")
     long countAll();
 }
 
 @Repository
-// @Transactional is not needed, only here for clarity since we want the repo to always be called from a tx context
+// @Transactional is not needed but here for clarity since we want repos to always be called from a tx context
 @Transactional(propagation = MANDATORY)
 class PagedAccountRepositoryImpl implements PagedAccountRepository {
     @Autowired
@@ -262,15 +268,17 @@ public Page<Account> findAll(Pageable pageable) {
 /**
  * The main account repository, notice there's no implementation needed since its auto-proxied by
  * spring-data.
+ * <p>
+ * Should have extended PagingAndSortingRepository in normal cases.
  */
 @Repository
 @Transactional(propagation = MANDATORY)
 interface AccountRepository extends CrudRepository<Account, Long>, PagedAccountRepository {
-    @Query(value = "select balance from account where id=:id")
+    @Query(value = "SELECT balance FROM account WHERE id=:id")
     BigDecimal getBalance(@Param("id") Long id);
 
     @Modifying
-    @Query("update account set balance = balance + :balance where id=:id")
+    @Query("UPDATE account SET balance = balance + :balance WHERE id=:id")
     void updateBalance(@Param("id") Long id, @Param("balance") BigDecimal balance);
 }
 
@@ -285,7 +293,7 @@ public NegativeBalanceException(String message) {
 }
 
 /**
- * Annotation marking a transaction boundary to use time travel.
+ * Annotation marking a transaction boundary to use follower reads (time travel).
  * See https://www.cockroachlabs.com/docs/stable/follower-reads.html
  */
 @Inherited
@@ -299,12 +307,16 @@ public NegativeBalanceException(String message) {
 /**
  * Main remoting and transaction boundary in the form of a REST controller. The discipline
  * when following the entity-control-boundary (ECB) pattern is that only service boundaries
- * are allowed to start and end transactions. That is enforced by the REQUIRES_NEW propagation
- * attribute of transactional controller methods. Between the web container's HTTP listener
- * and the transaction proxy there's also another transparent proxy in the form of a
- * retry loop advice with exponential backoff. It takes care of retrying transactions that
- * are aborted by transient SQL errors, rather than having these propagate all the way
- * over the wire to the HTTP client. See RetryableTransactionAspect below.
+ * are allowed to start and end transactions. A service boundary can be a controller, business
+ * service facade or service activator (JMS/Kafka listener).
+ * <p>
+ * This is enforced by the REQUIRES_NEW propagation attribute of @Transactional annotated
+ * controller methods. Between the web container's HTTP listener and the transaction proxy,
+ * there's yet another transparent proxy in the form of a retry loop advice with exponential
+ * backoff. It takes care of retrying transactions that are aborted by transient SQL errors,
+ * rather than having these propagate all the way over the wire to the client / user agent.
+ *
+ * @see RetryableTransactionAspect
  */
 @RestController
 class AccountController {
@@ -325,10 +337,11 @@ public ResponseEntity<RepresentationModel> index() {
         // Type-safe way to generate URLs bound to controller methods
         index.add(linkTo(methodOn(AccountController.class)
                 .listAccounts(PageRequest.of(0, 5)))
-                .withRel("accounts"));
+                .withRel("accounts")); // Lets skip curies and affordances for now
 
-        // This essentially informs the client that a POST to a href with this rel
-        // and value parameters will transfer funds between accounts.
+        // This rel essentially informs the client that a POST to its href with
+        // form parameters will transfer funds between referenced accounts.
+        // (its only a demo)
         index.add(linkTo(AccountController.class)
                 .slash("transfer{?fromId,toId,amount}")
                 .withRel("transfer"));
@@ -350,7 +363,7 @@ public ResponseEntity<RepresentationModel> index() {
      */
     @GetMapping("/account")
     @Transactional(propagation = REQUIRES_NEW)
-    @TimeTravel
+    @TimeTravel // We dont need the result to be authoritative, so any follower replica can service the read
     public HttpEntity<PagedModel<AccountModel>> listAccounts(
             @PageableDefault(size = 5, direction = Sort.Direction.ASC) Pageable page) {
         return ResponseEntity
@@ -361,7 +374,7 @@ public HttpEntity<PagedModel<AccountModel>> listAccounts(
      * Provides a point lookup of a given account.
      */
     @GetMapping(value = "/account/{id}")
-    @Transactional(propagation = REQUIRES_NEW, readOnly = true)
+    @Transactional(propagation = REQUIRES_NEW, readOnly = true) // Notice its marked read-only
     public HttpEntity<AccountModel> getAccount(@PathVariable("id") Long accountId) {
         return new ResponseEntity<>(accountModelAssembler().toModel(
                 accountRepository.findById(accountId)

jooq/README.md

@@ -1,10 +1,10 @@
 # Roach Demo Data :: jOOQ
 
-Spring Boot Demo using CockroachDB with jOOQ.
+A CockroachDB Spring Boot Demo using [jOOQ](https://www.jooq.org/) for data access.
 
 ## Generate jOOQ classes
 
-First create a DB schema:
+First create the DB schema:
 
     create table account
     (
@@ -14,21 +14,13 @@ First create a DB schema:
         type    varchar(25)    not null
     );
 
-Then generate the code by activating a Maven profile called generate:
+Then generate code by activating a Maven profile called _generate_:
 
     mvn -P generate clean install
 
 (Note: this will fail with an error when using CRDB even if classes are generated correctly)    
 
-Finally drop the table:
+Finally drop the table
 
     drop table account cascade;
 
-## Run
-
-    java -jar target/roach-demo-data.jar
-
-Run with custom db URL:
-
-    java -jar target/roach-demo-data.jar --spring.datasource.url=jdbc:postgresql://localhost:26257/roach_demo_data?sslmode=disable
-    

jpa/README.md

@@ -1,12 +1,12 @@
 # Roach Demo Data :: JPA/Hibernate
 
-Spring Boot Demo using CockroachDB with JPA/Hibernate.
-    
-## Run
-
-    java -jar target/roach-demo-data.jar
+A CockroachDB Spring Boot Demo using [Spring Data JPA](https://spring.io/projects/spring-data-jpa)
+with Hibernate for data access.
 
-With a custom DB URL:
+Spring Data JPA provides a powerful model for using ORM frameworks such as Hibernate. It's considered a good 
+fit for data access logic that involve large, complex domain model mapping. Spring Data JPA essentially
+removes the need for application code to bind directly to Hibernate APIs. It also unlocks many advanced 
+features of JPA.
+    
 
-    java -jar target/roach-demo-data.jar --spring.datasource.url=jdbc:postgresql://localhost:26257/roach_demo_data?sslmode=disable
-    
+        

jpa/src/main/java/io/roach/demo/data/JpaApplication.java

@@ -155,7 +155,7 @@ enum AccountType {
 
 @Entity
 @Table(name = "account")
-class AccountEntity {
+class Account {
     @Id
     @Column
     @GeneratedValue(strategy = GenerationType.IDENTITY)
@@ -223,14 +223,14 @@ public void setBalance(BigDecimal balance) {
 
 @Repository
 @Transactional(propagation = MANDATORY)
-interface AccountRepository extends JpaRepository<AccountEntity, Long>,
-        JpaSpecificationExecutor<AccountEntity> {
+interface AccountRepository extends JpaRepository<Account, Long>,
+        JpaSpecificationExecutor<Account> {
 
-    @Query(value = "select balance from AccountEntity where id=?1")
+    @Query(value = "select balance from Account where id=?1")
     BigDecimal getBalance(Long id);
 
     @Modifying
-    @Query("update AccountEntity set balance = balance + ?2 where id=?1")
+    @Query("update Account set balance = balance + ?2 where id=?1")
     void updateBalance(Long id, BigDecimal balance);
 }
 
@@ -247,7 +247,7 @@ class AccountController {
     private AccountRepository accountRepository;
 
     @Autowired
-    private PagedResourcesAssembler<AccountEntity> pagedResourcesAssembler;
+    private PagedResourcesAssembler<Account> pagedResourcesAssembler;
 
     @GetMapping
     public ResponseEntity<RepresentationModel> index() {
@@ -305,7 +305,7 @@ public HttpEntity<BigDecimal> transfer(
         return ResponseEntity.ok().build();
     }
 
-    private RepresentationModelAssembler<AccountEntity, AccountModel> accountModelAssembler() {
+    private RepresentationModelAssembler<Account, AccountModel> accountModelAssembler() {
         return (entity) -> {
             AccountModel model = new AccountModel();
             model.setName(entity.getName());

mybatis/README.md

@@ -1,12 +1,5 @@
 # Roach Demo Data :: MyBatis
 
-Spring Boot Demo using CockroachDB with MyBatis/JDBC.
-
-## Run
-
-    java -jar target/roach-demo-data.jar
-
-With a custom db URL:
-
-    java -jar target/roach-demo-data.jar --spring.datasource.url=jdbc:postgresql://localhost:26257/roach_demo_data?sslmode=disable
-    
+A CockroachDB Spring Boot Demo using [MyBatis](https://mybatis.org/mybatis-3/)
+integrated with [Spring Data JDBC](https://docs.spring.io/spring-data/jdbc/docs/1.1.6.RELEASE/reference/html/#jdbc.mybatis) 
+for data access.

mybatis/src/main/java/io/roach/demo/data/MyBatisApplication.java

@@ -263,7 +263,7 @@ interface AccountRepository extends CrudRepository<Account, Long>, PagedAccountR
     @Query("SELECT balance FROM account WHERE id = :id")
     BigDecimal getBalance(@Param("id") Long id);
 
-    @Query("UPDATE Account set balance = balance + :balance where id=:id")
+    @Query("UPDATE account SET balance = balance + :balance WHERE id=:id")
     @Modifying
     void updateBalance(@Param("id") Long id, @Param("balance") BigDecimal balance);
 }