Documentation

Author: jeffgbutler

src/site/markdown/docs/mybatis3.md

@@ -5,26 +5,50 @@ The goal of this support is to reduce the amount of boilerplate code needed for
 
 With version 1.1.3, specialized interfaces and utilities were added that can further simplify client code. This support enables the creation of methods that have similar functionality to some of the methods generated in previous versions of MyBatis generator like countByExample, deleteByExample, and selectByExample. We no longer use the "by example" terms for these methods as this library has eliminated the Example class that was generated by prior versions of MyBatis Generator.
 
-## Dynamic Result Mapping Support
-MyBatis is very good at mapping result sets to objects - this is one of its primary differentiators. MyBatis also requires
-that you predefine the mappings for every possibility. This presents a challenge if you want very dynamic column lists
-in a query. This library provides a generalized MyBatis mapper that can assist with that problem.
-
-The general mapper is `org.mybatis.dynamic.sql.util.mybatis3.CommonSelectMapper`. This mapper can be injected into a MyBatis configuration
-as is, or it can be extended by an existing mapper. If you are using MyBatis Spring support and auto scanning for mappers,
-you can create an extension in your application's mapper package as follows:
+## Common Mapper Support
+The library includes several common mappers for MyBatis that can be injected into a MyBatis configuration as-is, or can be
+extended. These mappers can be used to eliminate repetitive boilerplate code for several operations - namely count queries,
+deletes, inserts, and updates. In addition, there is a common select mapper that can be used to avoid writing custom
+result maps for every query. The common select mapper provides a row mapper function that is very similar to Spring
+JDBC template.
+
+### Common Count, Delete, Insert, and Update Mappers
+These mappers provide utility functions that execute simple queries. They can be used as-as, or can be extended. They
+provide methods as follows:
+
+Mapper | Methods(s)
+---|---
+`org.mybatis.dynamic.sql.util.mybatis3.CommonCountMapper` | `long count(SelectStatementProvider)`
+`org.mybatis.dynamic.sql.util.mybatis3.CommonDeleteMapper` | `int delete(DeleteStatementProvider)`
+`org.mybatis.dynamic.sql.util.mybatis3.CommonInsertMapper<T>` | `int insert(InsertStatementProvider<T>)`<br/>`int generalInsert(GeneralInsertStatementProvider)`<br/>`int insertSelect(InsertSelectStatementProvider)`<br/>`int insertMultiple(MultiRowInsertStatementProvider<T>)`
+`org.mybatis.dynamic.sql.util.mybatis3.CommonUpdateMapper` | `int update(UpdateStatementProvider)`
+
+These mappers, as well as the common selectmapper, can be used to create a general purpose CRUD mapper as follows:
 
 ```java
-package foo.mapper;
-
 import org.apache.ibatis.annotations.Mapper;
+import org.mybatis.dynamic.sql.util.mybatis3.CommonCountMapper;
+import org.mybatis.dynamic.sql.util.mybatis3.CommonDeleteMapper;
+import org.mybatis.dynamic.sql.util.mybatis3.CommonInsertMapper;
 import org.mybatis.dynamic.sql.util.mybatis3.CommonSelectMapper;
+import org.mybatis.dynamic.sql.util.mybatis3.CommonUpdateMapper;
 
 @Mapper
-public interface MyGeneralMapper extends CommonSelectMapper {
+public interface FooMapper extends CommonCountMapper, CommonDeleteMapper, CommonInsertMapper<Foo>, CommonSelectMapper,
+        CommonUpdateMapper {
 }
 ```
 
+This mapper can be extended with default methods as shown below. 
+
+### Common Select Mapper
+MyBatis is very good at mapping result sets to objects - this is one of its primary differentiators. MyBatis also requires
+that you predefine the mappings for every possibility. This presents a challenge if you want very dynamic column lists
+in a query. This library provides a generalized MyBatis mapper that can assist with that problem.
+
+The general mapper is `org.mybatis.dynamic.sql.util.mybatis3.CommonSelectMapper`. This mapper can be injected into a MyBatis configuration
+as is, or it can be extended by an existing mapper.
+
 The mapper contains three types of methods:
 
 1. The `selectOneMappedRow` and `selectManyMappedRows` methods allow you to use select statements with
@@ -111,10 +135,11 @@ import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
 import org.mybatis.dynamic.sql.util.mybatis3.CommonSelectMapper;
 
 public class MyService {
-    public Long getCount() {
+    public Long getAverageAge() {
         CommonSelectMapper mapper = getGeneralMapper(); // not shown
 
-        SelectStatementProvider selectStatement = countFrom(foo)
+        SelectStatementProvider selectStatement = select(avg(age))
+            .from(foo)
             .where(description. isLike("%bar%"))
             .build()
             .render(RenderingStrategies.MYBATIS3);
@@ -134,7 +159,10 @@ To use this support, we envision creating several methods on a MyBatis mapper in
 long count(SelectStatementProvider selectStatement);
 ```
 
-This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `long`. The other methods will reuse this method and supply everything needed to build the select statement except the where clause. There are several variants of count queries that may be useful:
+This is a standard method for MyBatis Dynamic SQL that executes a query and returns a `long`. The other methods will reuse
+this method and supply everything needed to build the select statement except the where clause. In lieu of writing this method,
+you could extend `org.mybatis.dynamic.sql.util.mybatis3.CommonCountMapper` instead. There are several variants
+of count queries that may be useful:
 
 1. `count(*)` - counts the number of rows that match a where clause
 1. `count(column)` - counts the number of non-null column values that match a where clause
@@ -180,7 +208,9 @@ To use this support, we envision creating two methods on a MyBatis mapper interf
 int delete(DeleteStatementProvider deleteStatement);
 ```
 
-This is a standard method for MyBatis Dynamic SQL that executes a delete and returns an `int` - the number of rows deleted. The second method will reuse this method and supply everything needed to build the delete statement except the where clause:
+This is a standard method for MyBatis Dynamic SQL that executes a delete and returns an `int` - the number of rows deleted.
+In lieu of writing this method, you could extend `org.mybatis.dynamic.sql.util.mybatis3.CommonDeleteMapper` instead. 
+The second method will reuse this method and supply everything needed to build the delete statement except the where clause:
 
 ```java
 default int delete(DeleteDSLCompleter completer) {
@@ -218,7 +248,9 @@ int generalInsert(GeneralInsertStatementProvider insertStatement);
 int insertMultiple(MultiRowInsertStatementProvider<PersonRecord> insertStatement);
 ```
 
-These methods are standard methods for MyBatis Dynamic SQL. They execute a single row insert, a general insert, and a multiple row insert.
+These methods are standard methods for MyBatis Dynamic SQL. They execute a single row insert, a general insert, and a
+multiple row insert. In lieu of writing these methods, you could extend
+`org.mybatis.dynamic.sql.util.mybatis3.CommonInsertMapper` instead. 
 
 These methods can be used to implement simplified insert methods:
 
@@ -357,7 +389,10 @@ To use this support, we envision creating several methods on a MyBatis mapper in
 int update(UpdateStatementProvider updateStatement);
 ```
 
-This is a standard method for MyBatis Dynamic SQL that executes a query and returns an `int` - the number of rows updated. The second method will reuse this method and supply everything needed to build the update statement except the values and the where clause:
+This is a standard method for MyBatis Dynamic SQL that executes a query and returns an `int` - the number of rows updated.
+In lieu of writing this method, you could extend `org.mybatis.dynamic.sql.util.mybatis3.CommonUpdateMapper` instead. 
+The second method will reuse this method and supply everything needed to build the update statement except the values
+and the where clause:
 
 ```java
 default int update(UpdateDSLCompleter completer) {